home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 7 / BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso / Files / MacII / M-P / MandelZot 3.0 docs .cpt / ECI.h next >
Text File  |  1990-09-26  |  15KB  |  406 lines
  1. /*
  2.         Data definitions for the MandelZot external function
  3.         interface.
  4. */
  5.  
  6. #include <MacTypes.h>
  7.  
  8. #define ECIVERSION 0x0100        /* version 1.0 per Apple's numbering style */
  9.  
  10. typedef union Arg                        /* Argument variants */
  11.     {
  12.         void                 *p;                        /* generic pointer */
  13.         Handle                h;                        /* generic handle */
  14.         char                    c;                        /* single character */
  15.         char                    bool;                    /* one-byte boolean */
  16.         short int            si;                        /* 16-bit integer */
  17.         long int            li;                        /* 32-bit integer */
  18.         long int            flags;                /* 32 one-bit flags */
  19.         float                    f;                        /* SANE/IEEE single-precision floating */
  20.         short double  d;                        /* SANE/IEEE double-precision floating */
  21.         double                e;                        /* SANE *or* IEEE extended-precision */
  22.         Rect                    r;                        /* QuickDraw rectangle */
  23.         char                    filler[12];
  24.     } Arg;
  25.  
  26. typedef struct ECD                    /* External Code descriptor */
  27.     {
  28.         Handle                private;            /* handle to module-specific private data, if any */
  29.         int                        resFileRefNum;/* refNum of resource file, if open... or 0 */
  30.         long int            opaque[];            /* remainder of structure is opaque to the ECM */
  31.     } ECD, **ECDHandle;
  32.  
  33. typedef struct ECP                    /* External Code parameter structure */
  34.     {
  35.         long int            functionCode;    /* function code being requested */
  36.         Arg                        arg[16];            /* up to 16 arguments per call */
  37.     } ECP, **ECPHandle;
  38.  
  39. typedef struct ECO                    /* External Code overhead structure */
  40.     {
  41.         ECDHandle            ECD;                    /* handle to code descriptor structure */
  42.         Handle                viewHandle;        /* opaque handle to view structure */
  43.         Handle                private;            /* handle to view-specific private data, if any */
  44.         long int            (*util)();        /* pointer to MandelZot "pascal" utility callback */
  45.     } ECO, **ECOHandle;
  46.  
  47. /*
  48.         Data bits describing ECM's requirements
  49. */
  50.  
  51. #define NeedFPU                        0x80000000
  52. #define NeedIEEEformat        0x40000000
  53. #define NeedResources            0x20000000
  54. #define NeedLockSelf            0x10000000
  55. #define NeedLockAll                0x08000000
  56. #define NeedConfigure            0x04000000
  57.  
  58. /*
  59.         Data bits describing ECM's capabilities
  60. */
  61.  
  62. #define DoMarianiSilver        0x80000000
  63. #define DoDistEstimator        0x40000000
  64. #define DoJulias                    0x20000000
  65. #define DoByPoint                    0x10000000
  66. #define DoByBatch                    0x08000000
  67.  
  68. /*
  69.         Data bits describing symmetry
  70. */
  71.  
  72. #define SymmetryHoriz            0x0001
  73. #define SymmetryVert            0x0002
  74. #define SymmetryOrigin        0x0004
  75.  
  76. /*
  77.         Data bits describing math modes supported/used
  78. */
  79.  
  80. #define Math16bit                    0x0001
  81. #define Math32bit                    0x0002
  82. #define MathSANE                    0x0004
  83. #define Math881                        0x0008
  84.  
  85. /*
  86.         Values returned from the CalcTimeSlice call
  87. */
  88.  
  89. #define SliceSuspend            -1
  90. #define SliceOK                        0
  91. #define SliceIdle                    1
  92. #define SliceDone                    2
  93.  
  94. /*
  95.         File and resource types etc.
  96. */
  97.  
  98. #define CustomFileType        'CUST'
  99. #define CustomResType            'CUST'
  100. #define CustomResID                0
  101. #define CustomResRange        1024
  102. #define CustomResRangeEnd    2047
  103.  
  104. /*
  105.         Values and masks for dwell counts.
  106.         
  107.         Dwell values are stored in 16-bit integers.  The rightmost 15 bits
  108.         are the dwell value (in the range 0 through 32765), or "in the M-set"
  109.         (32766) or "unknown at this time" (32767).  The leftmost bit is a flag
  110.         used to indicate that the value in the rightmost 15 bits is approximate
  111.         or inexact, and should be recalculated;  this bit is set when a window is
  112.         resized upwards, or the calculation parameters are changed.
  113.         
  114. */
  115.  
  116. #define MaxLegalDwell    32765
  117. #define InTheSet            32766
  118. #define Unknown                32767
  119. #define RecalcBit            0x8000
  120. #define DwellMask            0x7FFF
  121.  
  122. /*
  123.         Function codes passed in to ECM from the program
  124. */
  125.  
  126. enum ECFunction
  127.     {
  128.         GetGeneralInfo                = 0,
  129.         InitECM                                = 1,
  130.         GetDefaults                        = 2,
  131.         SetupView                            = 3,
  132.         ConfigureView                    = 4,
  133.         SetupCalcs                        = 5,
  134.         CalcsGo                                = 6,
  135.         CalcsStop                            = 7,
  136.         CalcOne                                = 8,
  137.         CalcTimeSlice                    = 9,
  138.         KillView                            = 10,
  139.         KillECM                                = 11,
  140.         GetViewInfo                        = 12,
  141.         InvalInternals                = 13,
  142.         GetViewString                    = 14
  143.     };
  144.  
  145. /*
  146.         Parameter definitions for the various callins
  147.         
  148.         "->" represents a value passed into the ECM
  149.         "<-" represents a value filled in by the ECM prior to returning.
  150.  
  151. ---
  152.  
  153.         GetGeneralInfo.  Called during program initialization.  ECM should fill in
  154.         specified values and return, taking no other actions.  [N.B.  This is the
  155.         only callin which can occur before the first InitECM.]
  156.  
  157.         [0].si            ->        Interface version against which program was compiled.
  158.         [0].si            <-        Interface version number against which the ECM was
  159.                                             compiled.  If too old, ECM will not be usable.
  160.         [1].flags        <-        "Needs" flags, or'ed together
  161.         [2].flags        <-        "Does" flags, or'ed together.
  162.         [3].flags        <-        "Math" flags, or'ed together
  163.  
  164. ---        
  165.         
  166.         InitECM.  Called when ECM's code resource is first read in.  ECM should set
  167.         up any desired global-state code, storing handle into the ECD structure.
  168.         
  169.         No data is passed in or out.
  170.  
  171. ---
  172.  
  173.         GetDefaults.  Called during the "New view" dialog, when an ECM is selected from
  174.         the popup menu, or when the julia-set status box changes.
  175.         
  176.         [0].bool        ->        if true, the ECM should return the appropriate default
  177.                                             values for a Julia-set image.  If false, the ECM should
  178.                                             return the appropriate defaults for an M-like image.
  179.         
  180.         [0].d                <-        Minimum real value displayed in window
  181.         [1].d                <-        Maximum real value displayed in window
  182.         [2].d                <-        Minimum imaginary value displayed in window
  183.         [3].d                <-        Maximum imaginary value displayed in window
  184.         [4].si            <-        Dwell limit [0..32765]
  185.         [5].d                <-        Escape radius
  186.         [6].d                <-        Julia control point, real (iff julia image requested)
  187.         [7].d                <-        Julia control point, imaginary (iff julia image requested)
  188.  
  189. ---
  190.  
  191.     ConfigureView.  Called when the user presses the "Setup" botton in the
  192.     New View dialog box (and also when the ECM is initially selected from
  193.     the popup menu).  The ECM may pop up a dialog box to allow
  194.     the user to enter configuration information (e.g. equation coefficients,
  195.     network-server name/ID, etc.).  All such data should be stored in a relocatable
  196.     block allocated by the ECM, whose handle is stored in the ECO structure.
  197.     This routine may be called multiple times, to update the configuration.
  198.     
  199.         [0].bool        ->        nonzero if Julia calculation, zero if M calculation
  200.  
  201. ---
  202.  
  203.     GetViewInfo.  Called after the view data structure has been initialized, and
  204.     before calculation begins.  ECM must return information about the characteristics
  205.     of the view:  whether the distance-estimator feature is available, whether the
  206.     Mariani-Silver algorithm should be enabled, information concerning the symmetry
  207.     of the resulting image, etc.
  208.  
  209.         [0].e                ->        Minimum real value displayed in window
  210.         [1].e                ->        Maximum real value displayed in window
  211.         [2].e                ->        Minimum imaginary value displayed in window
  212.         [3].e                ->        Maximum imaginary value displayed in window
  213.         [4].si            ->        Dwell limit [0..32765]
  214.         [5].d                ->        Escape radius
  215.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  216.         [7].e                ->        Julia control point, real (iff julia image requested)
  217.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  218.         
  219.         [0].bool         <-        nonzero if distance-estimator capability is available
  220.         [1].bool        <-        nonzero if Mariani/Silver algorithm is suitable
  221.         [2].flags        <-        symmetry characteristics: horizontal, vertical, across-origin,
  222.                                             or an or'ed combination thereof.
  223.         [3].e                <-        real axis of symmetry, if any symmetry is specified
  224.         [4].e                <-        imaginary axis of symmetry, if any symmetry is specified
  225.  
  226. ---
  227.  
  228.     SetupCalcs.  Called when the view data structure has been initialized, and
  229.     calculation is about to begin.  ECM should set up any data it needs to perform
  230.     the calculation, based on the current calculation parameters.  May be called
  231.     more than once, if the user changes the calculation parameters.
  232.     
  233.         [0].e                ->        Minimum real value displayed in window
  234.         [1].e                ->        Maximum real value displayed in window
  235.         [2].e                ->        Minimum imaginary value displayed in window
  236.         [3].e                ->        Maximum imaginary value displayed in window
  237.         [4].si            ->        Dwell limit [0..32765]
  238.         [5].d                ->        Escape radius
  239.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  240.         [7].e                ->        Julia control point, real (iff julia image requested)
  241.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  242.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  243.         [10].r            ->        Rectangle framing the window
  244.  
  245. ---
  246.  
  247.     CalcsGo.  Called when the program has decided to start calling CalcTimeSlicd.
  248.     ECM should grab any resources needed to do calculation (external hardware,
  249.     network calculation server, etc.).
  250.  
  251.     No parameters at this time;  success is assumed.
  252.  
  253. ---
  254.  
  255.     CalcsStop.  Called when the program has decided to stop calling CalcTimeSlice.
  256.     ECM should release any resources it grabbed at CalcsGo time.
  257.  
  258.     No parameters at this time;  success is assumed.
  259.  
  260. ---
  261.  
  262.     CalcOne.  Called to request calculation of the dwell (and, optionally,
  263.     distance-to-nearest-interior-point) of a single point.
  264.     
  265.         [0].e                ->         Real coordinate of point
  266.         [1].e                ->        Imaginary coordinate of point
  267.         [2].si            ->        Dwell limit
  268.         [3].d                ->        Escape radius
  269.         [4].bool        ->        nonzero if Julia calculation, zero if M calculation
  270.         [5].bool        ->        nonzero if distance-estimator, zero if point-by-point
  271.         [6].e                ->        Julia control point, real (iff julia image requested)
  272.         [7].e                ->        Julia control point, imaginary (iff julia image requested)
  273.         [8].flags        ->        Flag indicating math mode in use
  274.  
  275.         [0].si            <-        Dwell of point [0..limit), or
  276.                                             "on border" == limit, or
  277.                                             "in M"            == 32766 (InTheSet).
  278.         [1].e                <-        Estimated distance to nearest interior point (iff
  279.                                             distance-estimator mode), or -1 == "beats me!"
  280.  
  281. ---
  282.  
  283.     CalcTimeSlice.  Called to give a bulk-calculation-mode ECM an opportunity to
  284.     calculate something.  CalcTimeSlice calls will occur in the middle of a
  285.     CalcGo/CalcStop pair.  ECM should do some calculating, if possible;  stuff
  286.     dwell values into the array;  and use callbacks to instruct the program to
  287.     display points/lines/rectangles of data values on the screen.  ECM can draw to
  288.     the window if desired (it's the current GrafPort).
  289.     
  290.         [0].e                ->        Minimum real value displayed in window
  291.         [1].e                ->        Maximum real value displayed in window
  292.         [2].e                ->        Minimum imaginary value displayed in window
  293.         [3].e                ->        Maximum imaginary value displayed in window
  294.         [4].si            ->        Dwell limit [0..32765]
  295.         [5].d                ->        Escape radius
  296.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  297.         [7].e                ->        Julia control point, real (iff julia image requested)
  298.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  299.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  300.         [10].r            ->        Rectangle framing the window
  301.         [11].r            ->        Rect which frames entire array (if calculation is not currently
  302.                                             constrained) or frames constrained area.  ECM should limit its
  303.                                             calculations and drawing to points within this rectangle.
  304.         [12].h            ->        Handle to array of dwell values, stored in row-major order
  305.         [13].flags    ->        Flag indicating math mode in use
  306.         
  307.         [0].si            <-        SliceOK if all is well and useful work was done;
  308.                                             SliceIdle if all is well but nothing much happened (little time used);
  309.                                             SliceDone if all is well and calculations for the area framed by
  310.                                             the [11].r parameter have been completed;
  311.                                             SliceSuspend if something has gone awry and calculations should
  312.                                             be suspended until the user hits command-G again.
  313.  
  314. ---
  315.  
  316.     InvalInternals.  Called when MandelZot loads a view's private data from a save-
  317.     file, or after an "Extract selection" command.  Call informs ECM that any pointers
  318.     or handles stashed in the view's private data block are no longer valid... they may
  319.     point to the parent window's private data (after an "Extract selection) or to
  320.     memory locations from a former lifetime (after loading a save-file).  ECM should zap
  321.     any pointers or handles (reset them to NULL, or allocate new blocks of the necessary
  322.     sizes and replace the old handles).  ECM should _not_ attempt to access, or dispose of
  323.     blocks referenced by the invalidated handles or pointers... they're off limits!!
  324.         
  325. ---
  326.  
  327.     GetViewString.  Called when the program wants a human-readable interpretation
  328.     of the view's private data.  ECM should convert relevant portions of the
  329.     private data (e.g. polynomial coefficients, exit conditions, etc.) to printable
  330.     form, and return them in the form of a PASCAL string of up to 255 characters.
  331.     
  332.         [0].p                ->        Pointer to an Str255 (PASCAL string) of indeterminate
  333.                                             contents;  program should stuff string into this structure.
  334.  
  335. */
  336.  
  337. /*
  338.         Function codes which the ECM can use when calling back to the main program
  339. */
  340.  
  341. enum CallbackFunction
  342.     {
  343.         DisplayPoint                    = 100,
  344.         DisplayRowSeg                    = 101,
  345.         DisplayRect                        = 102,
  346.         SetPenColor                        = 103,
  347.         SetStatusString                = 104
  348.     };
  349.  
  350. /*
  351.         Parameter definitions for the various callbacks
  352.         
  353.         "->" represents a value passed by the ECM to the program's callback routine
  354.         "<-" represents a value filled in by the callback prior to returning.
  355.         
  356.         DisplayPoint.  Used to ask the program to display a specified dwell-point in the
  357.         window.  ECM must stuff the dwell value into the dwell array before making this
  358.         call.
  359.         
  360.         [0].si            ->        X coordinate of point to be displayed
  361.         [1].si            ->        Y coordinate of point to be displayed
  362.  
  363. ---
  364.  
  365.         DisplayRowSeg.  Used to ask the program to display one or more dwell
  366.         points in a specified row.  ECM must stuff the values into the dwell array before
  367.         making this call.
  368.         
  369.         [0].si            ->        X coordinate at left end of row segment.
  370.         [1].si            ->        X coordinate at right end of row segment.
  371.         [2].si            ->        Y coordinate of row.
  372.  
  373. ---
  374.  
  375.         DisplayRect.  Used to ask the program to display a rectangular portion of the
  376.         view window, using the current dwell values for those points.
  377.         
  378.         [0].r                ->        Rect specifying the area to be displayed.
  379.         
  380.         n.b. the display occurs when the call is made.  Another way to do this is to
  381.         simply InvalRect(&rect);  the program will erase and redraw the specified
  382.         rectangle the next time around the event loop.
  383.  
  384. ---
  385.  
  386.         SetPenColor.  Used to ask the program to set the port's pen to the proper
  387.         color for drawing points of a specific dwell.
  388.         
  389.         [0].r                ->        Dwell value for which pen color should be set.
  390.         
  391.         n.b. ECM should reset the pen to black before returning.
  392.  
  393. ---
  394.  
  395.         SetStatusString.  Used to ask the program to update the status advisory
  396.         displayed (sometimes) in the horizontal scroll bar area.
  397.         
  398.         [0].p                ->        Pointer to Pascal Str255 string to be displayed.
  399.         
  400.         n.b. the specified string may or may not actually be displayed, at this
  401.         time or later.  This feature should be used for "FYI" information only;
  402.         it's not suitable for use in developing any sort of real user interface.
  403.  
  404. */
  405.  
  406.